Saving Files

Navigation Services provides functions to save documents and to query the user about unsaved changes.

NavPutFile displays a Save dialog box.
NavAskSaveChanges displays a Save Changes alert box.
NavCustomAskSaveChanges displays a Save Changes alert box with a custom alert message.
NavAskDiscardChanges displays an alert box that asks the user whether to discard changes to a particular document.
NavCompleteSave completes a save operation and performs any needed translation on the file.

NavPutFile

Displays a Save dialog box.



 
OSErr NavPutFile    (AEDesc *defaultLocation,

                                         NavReplyRecord *reply,

                                         NavDialogOptions *dialogOptions,

                                         NavEventUPP eventProc,

                                         OSType fileType,

                                         OSType fileCreator,

                                         void *callBackUD);

defaultLocation: A pointer to an Apple event descriptor structure (AEDesc ). Before calling NavPutFile , you can set up a structure of AEDesc type'typeFSS' to specify a default location to be viewed. If you pass NULL in this parameter, Navigation Services displays the last location visited during a call to the NavPutFile function. If the file system specification in the AEDesc structure does not describe a directory or volume, Navigation Services uses the desktop as the default location.
reply: A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavPutFile call.
dialogOptions: A pointer to a structure of type NavDialogOptions . Before calling NavPutFile , you can set up this structure to specify dialog box settings. If you pass NULL in this parameter, Navigation Services uses the defaults for all options. see Configuration Option Constants for a description of the default settings.
eventProc: A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Save dialog box is not movable or resizable. For more information, see Handling Events .
fileType: A four-character code. Pass a file type code for the document to be saved.
fileCreator: A four-character code. Pass a file creator code for the document to be saved.
callBackUD: A pointer to a value set by your application. When the NavPutFile function calls your event-handling function, the callBackUD value is passed back to your application.
function result: see Result Codes for a list of result codes.

NOTE

If you specify the kNavDontResolveAliases constant as a dialog box option, as described in Configuration Option Constants , before calling the NavPutFile function, Navigation Services returns a paramErr (-50) .

DISCUSSION

After your application calls the NavPutFile function to display a Save dialog box and the user selects a location, enters a filename, and clicks OK, NavPutFile closes the dialog box and returns references to the file to be saved in the NavReplyRecord structure. Your application should check the validRecord field of the NavReplyRecord structure; if this field is set to true , your application should save the file and call the function NavCompleteSave .

If you specify the Format pop-up menu in a dialog box displayed by the NavPutFile function, your application must provide adequate kind strings to describe the file types available. If the user uses the Format menu to save a file to a format other than the file's native format, Navigation Services translates the file automatically. If you wish to turn off automatic translation, set to false the value of the translationNeeded field of the NavReplyRecord structure you pass in the reply parameter. If you turn off automatic translation, your application is responsible for any required translation.

NavAskSaveChanges

Displays a Save Changes alert box.



 
OSErr NavAskSaveChanges (NavDialogOptions *dialogOptions,

                        NavAskSaveChangesAction action,

                        NavAskSaveChangesResult *reply,

                        NavEventUPP eventProc,

                        void *callBackUD);

dialogOptions: A pointer to a structure of type NavDialogOptions . Before calling NavAskSaveChanges , set up this structure to specify dialog box settings. In this case, the clientName and savedFileName fields are the only two you must supply with values.
action: A value of type NavAskSaveChangesAction . Pass a constant describing the user action that prompted the Save Changes alert box. For a description of the constants, see Save Changes Request Constants.
reply: A pointer to a structure of type NavAskSaveChangesResult . On return, the value describes the user's response to the Save Changes alert box. For a description of the constants used to represent possible responses, see Save Changes Action Constants.
eventProc: A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Save Changes alert box is not movable. For more information, see Handling Events .
callBackUD: A pointer to a value set by your application. When the NavAskSaveChanges function calls your event-handling function, the callBackUD value is passed back to your application.
function result: see Result Codes for a list of result codes.

DISCUSSION

This function is useful when your application needs to display an alert when the user attempts to close a document or an application with unsaved changes.

NavCustomAskSaveChanges

Displays a Save Changes alert box with a custom alert message.



 
OSErr NavCustomAskSaveChanges(NavDialogOptions *dialogOptions,

                                         NavAskSaveChangesResult *reply,

                                         NavEventUPP eventProc,

                                         void *callBackUD);

dialogOptions: A pointer to a structure of type NavDialogOptions . Before calling NavCustomAskSaveChanges , set up this structure to specify dialog box settings. In this case, the message field is the only one you must supply with a value.
reply: A pointer to a structure of type NavAskSaveChangesResult . On return, the value describes the user's response to the Save Changes alert box. For a description of the constants used to represent possible responses, see Save Changes Action Constants.
eventProc: A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Save Changes alert box is not movable. For more information, see Handling Events .
callBackUD: A pointer to a value set by your application. When the NavCustomAskSaveChanges function calls your event-handling function, the callBackUD value is passed back to your application.
function result: see Result Codes for a list of result codes.

DISCUSSION

This function is similar to the function NavAskSaveChanges , except you provide a custom alert message. This function is useful when you need to post a Save Changes alert box at times other than quitting or closing a file. Your application can display this alert box if a specified time interval has passed since the user last saved changes, for example.

NavAskDiscardChanges

Displays an alert box that asks the user whether to discard changes to a particular document.



 
OSErr NavAskDiscardChanges (NavDialogOptions *dialogOptions,

                                         NavAskDiscardChangesResult *reply,

                                         NavEventUPP eventProc,

                                        -!

dialogOptions: A pointer to a structure of type NavDialogOptions . Before calling NavAskDiscardChanges , set up this structure to specify dialog box settings. In this case, the savedFileName field is the only one you must supply with a value.
reply: A pointer to a structure of type NavAskDiscardChanges . On return, the value describes the user's response to the Discard Changes alert box. For a description of the constants used to represent possible responses, see Discard Changes Action Constants.
eventProc: A Universal Procedure Pointer (UPP) of type NavEventProcPtr that points to your application-defined event-handling function. Obtain this UPP by calling the function NewNavEventProc . Implementing an event-handling function allows your application to update windows after the user moves or resizes the dialog box. If you pass NULL in this parameter, the Discard Changes alert box is not movable. For more information, see Handling Events .
callBackUD: A pointer to a value set by your application. When the NavGetFile function calls your event-handling function, the callBackUD value is passed back to your application.
function result: see Result Codes for a list of result codes.

DISCUSSION

If your application provides a Revert to Saved command, you can use the NavAskDiscardChanges function to display a confirmation alert box when a user selects Revert to Saved for a document with unsaved changes. Navigation Services uses the string you supply in the savedFileName field of the NavDialogOptions structure you passed in the dialogOptions parameter to display the alert message, "Discard changes to <savedFilename>?".

NavCompleteSave

Completes a save operation and performs any needed translation on the file.



 
OSErr NavCompleteSave (NavReplyRecord *translateInfo,

                                         NavTranslateOptions howToTranslate);

translateInfo: A pointer to a structure of type NavReplyRecord . Upon return, Navigation Services uses this structure to provide data to your application about the results of your NavCompleteSave call.
howToTranslate: A pointer to a structure of type NavTranslationOptions . Pass one of two values to specify how to perform any needed translation. For a description of the constants you can use to represent these values, see Translation Option Constants. Translating in-place causes the source file to be replaced by the translation. Translating to a copy results in a file name followed by the string "(converted)" to avoid unwanted replacement. If you call the NavCompleteSave function in response to a Save a Copy command, you should pass the kNavTranslateInPlace constant in this parameter.
function result: see Result Codes for a list of result codes. Since this function performs any needed translation, it may return a translation error.

DISCUSSION

You should always call NavCompleteSave to complete any file saving operation performed with the NavPutFile function. NavCompleteSave performs any needed translation, so you do not have to use the function NavTranslateFile when saving. If you wish to turn off automatic translation, set to false the value of the translationNeeded field of the NavReplyRecord structure you pass in the reply parameter of the NavPutFile function. If you turn off automatic translation, your application is responsible for any required translation. For more information, see Saving Files.

Saving Files

NavPutFile

NOTE

DISCUSSION

SEE ALSO

NavAskSaveChanges

DISCUSSION

NavCustomAskSaveChanges

DISCUSSION

NavAskDiscardChanges

DISCUSSION

NavCompleteSave

DISCUSSION

SEE ALSO